
/*! \page secureinstallown Building a Secure Installation around a New Broker
 *
 * \htmlonly <script type="text/javascript">var randomUser1=Math.floor(Math.random()*1000000);var randomUser2=Math.floor(Math.random()*1000000);</script> \endhtmlonly
 * 
 * \section securesectionown Securing Your Broker
 * 
 * In order to run outside the confines of your local machine, the
 * broker must be secured with cryptographic keys. To do this, follow
 * the step outlined below, given that you have already completed the
 * steps in the \ref quickstart.
 * 
 * Depending on what you want from Acquire, use either 
 * the instructions on this page to build your own complete broker and 
 * user client system (generally, you would want to use an existing
 * system), or build the client parts to pair with an with an existing
 * system, as outlined in \ref secureinstallexisting.
 * 
 * Please remember, if the default directory
 * <tt>/usr/local</tt> is to be used, the installation process must be
 * run as <tt>root</tt>.
 * 
 * \subsection generatelocalkey Building a New Broker Server
 * 
 * To build a secure system, you must first generate a new master key
 * and propagate it through the system.  To reset the broker to a
 * state from which it will automatically generate a new master broker
 * key, first any installed databases must be deleted. On the
 * default install this can be achieved using: <p><tt>rm
 * ~/.AcquireLib5/*.db ~/.AcquireLib5/*.sql</tt><p> Navigate
 * to the '<tt>build</tt>' directory. Ensure that the keys and any
 * databases here are also removed with
 * <p><tt>rm *.sql *.db broker.enc broker.chk</tt><p>
 * Then ensure that the CMake options
 * are appropriate, notably:<ul> <li>the <tt>DOWNLOAD_NEW_KEYS</tt>
 * option is set to <tt>OFF</tt></li> <li>the
 * <tt>INSECURE_TEST_KEYS</tt> option is set to <tt>OFF</tt></li>
 * <li>the
 * <tt>INSECURE_PASSWORDS</tt> option is set to <tt>OFF</tt> <i>(strongly recommended, but not necessary)</i></li>
 * <li>the install path in <tt>CMAKE_INSTALL_PREFIX</tt> is
 * correct</li><li>the hostname in <tt>DEFAULT_HOST</tt> is set
 * to the host you want to download keys from</li><li>the port
 * number in <tt>DEFAULT_PORT</tt> is set to the broker port
 * that you want public keys for</li>
 * </ul> by invoking the CMake GUI using: <p><tt>ccmake
 * .</tt><p> pressing 'c' and 'g' to configure, generate and exit.
 * Now the broker server can be built using <p><tt>cmake .; make</tt><p>
 * now execute<p><tt>make install</tt><p>which will make the
 * important installation directory structure, but fail part way
 * through because there are no keys for client use.
 * 
 * For the
 * installation to be completed, in which the client is also valid,
 * run your new broker in another terminal window (to generate new
 * master keys and serve up the public keys). This can be done with:
 * <p><tt>./broker</tt><p>
 * which depending on your options may require you to choose passwords
 * to secure it. Wait for the broker to say that it is listening.
 * Then, once this is running elsewhere, in your original
 * build directory, change the build options a second time with:
 * <p><tt>ccmake .</tt><p>
 * and ensure that (as in \ref generateclient):
 * <ul> <li>the <tt>DOWNLOAD_NEW_KEYS</tt>
 * option is set to <tt>ON</tt></li>
 * </ul> <b>Do not change any other options.</b>
 * Press 'c' to save and configure. This should have obtained some new keys.
 * <b>Stop the broker now</b>.
 * Follow this with:
 * <p><tt>make; make install</tt><p> to complete the secure
 * installation. The appropriate broker keys will
 * now be installed alongside your newly built and paired client.
 * 
 * Please note that if you are planning to use the test sections
 * again, the
 * network database is now blank and needs cluster definitions. If
 * only testing is desired, override the cluster definitions for the
 * single-session with:
 * <p><tt>./broker \-\-override-clusters-for-this-session &lt;<i>path to installed files</i>&gt;/test_cluster.xml</tt><p>
 * before trying to do the tests.
 * 
 * At this point you can perform the tests again,
 * although with possibly different broker hosts and ensuring that
 * your username does not clash with other users.
 * 
 * \subsection tinned_cxx4 Initial Testing using the C++ Command Line Interface
 * 
 * This section tests the C++ command line client frontend for the
 * Acquire system. An example workpacket to submit is provided in the
 * '<tt>test_workpacket</tt>' subdirectory in the build directory.  It
 * is assumed that these tests are run from the build directory.
 * 
 * To run a job, first SSH-accessible machines must be added to the
 * system, either to act as gateways or machines on which cluster work
 * queues are accessible. By adding such a machine to a username
 * successfully, a user account is remotely created.
 * 
 * To add a new SSH machine via the C++ interface, use:
 * <p><tt>./acquire -u \htmlonly<script type="text/javascript">document.write("test" + randomUser1);</script>\endhtmlonly
 * -n 127.0.0.1 -p 10000 -A</tt><p>
 * 
 * When asked for a hostname use '127.0.0.1' as the 'test' cluster
 * is associated with this machine name. Then type in your local
 * SSH username and password. If this works then you should see a message
 * stating that the machine has been successfully added to Acquire.
 * If you do not see this message try again and ensure that your
 * username and password are correct and that the local SSH server
 * is correctly set up and the credentials you have entered are correct.
 * 
 * A datastore can now be created around a directory that contains the
 * work that you want to run remotely. To create a remote datastore,
 * choose the directory containing the workpacket and upload a
 * description of the data so that the broker can ensure that there is
 * enough space and the data will be secure. This can be achieved
 * using: <p><tt>./acquire -u \htmlonly<script type="text/javascript">document.write("test" + randomUser1);</script>\endhtmlonly -n 127.0.0.1 -p 10000 -d
 * ./test_workpacket/ -C</tt><p>
 * 
 * This creates a remote datastore which by default will have the
 * handle '&lt;user&gt;.workdata1', so in this case
 * \htmlonly<script type="text/javascript">document.write("\'test" + randomUser1 + ".workdata1\'");</script>\endhtmlonly. The view all the actors currently active, use:
 * 
 * <p><tt>./acquire -u \htmlonly<script type="text/javascript">document.write("test" + randomUser1);</script>\endhtmlonly -n 127.0.0.1 -p 10000 -T
 * </tt><p> This shows a tree view of the active items. To upload the
 * work data to the newly created
 * datastore, use:
 * 
 * <p><tt>./acquire -u \htmlonly<script type="text/javascript">document.write("test" + randomUser1);</script>\endhtmlonly -n 127.0.0.1 -p 10000 -d
 * ./test_workpacket/ -r \htmlonly<script type="text/javascript">document.write("\'test" + randomUser1 + ".workdata1\'");</script>\endhtmlonly -U</tt><p> This both
 * uploads and marks the data as 'work', prompting the broker to then
 * choose a cluster from those you have made accessible to the system,
 * to which the work is then submitted. Once the work is complete, to
 * get results, one must navigate the job hierarchy again. Use again:
 * <p><tt>./acquire -u \htmlonly<script type="text/javascript">document.write("test" + randomUser1);</script>\endhtmlonly -n 127.0.0.1 -p 10000 -T</tt><p>This command
 * gives the status of the work. This should be complete when the
 * 'instance1' child of your workdata has reached the 'finished' state. See
 * that the first workdata has created a child instance, and that that
 * child instance, once complete, has gone on to create another
 * workdata. To download this data, use:<p><tt>mkdir -p
 * \htmlonly<script type="text/javascript">document.write("/tmp/test" + randomUser1 + "_workpacket_output");</script>\endhtmlonly; ./acquire -u \htmlonly<script type="text/javascript">document.write("test" + randomUser1);</script>\endhtmlonly -n 127.0.0.1 -p
 * 10000 -d \htmlonly<script type="text/javascript">document.write("/tmp/test" + randomUser1 + "_workpacket_output");</script>\endhtmlonly/ -r
 * \htmlonly<script type="text/javascript">document.write("\'test" + randomUser1 + ".workdata1.instance1.workdata1\'");</script>\endhtmlonly -D</tt><p> Any data store
 * which you own and have keys for should be downloadable in this way.
 * After successfully downloading the workpacket, in the
 * <tt>\htmlonly<script type="text/javascript">document.write("\'/tmp/test" + randomUser1 + "_workpacket_output");</script>\endhtmlonly</tt>' directory you should have a
 * file '<tt>work_completed.txt</tt>' which contains a message stating
 * that the test workpacket has been completed.
 * 
 * \subsection tinned_python4 Initial Testing using the Python Command Line Interface
 * 
 * Similarly to the C++ user-facing client, SSH-accessible machines
 * must be added to the system for work to be done. This can instead
 * be achieved by using: <p><tt>python ./acquire.py -b broker -u \htmlonly<script type="text/javascript">document.write("test" + randomUser2);</script>\endhtmlonly -n
 * 127.0.0.1 -p 10000 -t hello -m &lt;<i>username</i>&gt;@127.0.0.1
 * -A</tt><p> (substituting your username into this command). This adds
 * the SSH login '&lt;username&gt;@127.0.0.1' to the user account
 * \htmlonly<script type="text/javascript">document.write("\'test" + randomUser2 + "\'");</script>\endhtmlonly on the broker. If the user does not exist, it will be
 * created. The password for the remote account is 'hello' here to
 * expedite batch processing. Once logins to clusters have been added,
 * the upload and submission can be done in a single command:
 * <p><tt>python ./acquire.py -b broker -u \htmlonly<script type="text/javascript">document.write("test" + randomUser2);</script>\endhtmlonly -n 127.0.0.1 -p 10000 -t
 * hello -d ./test_workpacket/ -S</tt><p> Then, as before, the
 * structure can be probed by showing the nodes in the tree
 * structure. <p><tt>python ./acquire.py -b broker -u \htmlonly<script type="text/javascript">document.write("test" + randomUser2);</script>\endhtmlonly -n 127.0.0.1
 * -p 10000 -t hello -T</tt><p>Finally, downloading the contents of
 * the ultimate child node (the datastore containing results) can be
 * achieved with: <p><tt>mkdir -p \htmlonly<script type="text/javascript">document.write("/tmp/test" + randomUser2 + "_workpacket_output/");</script>\endhtmlonly;
 * python ./acquire.py -b broker -u \htmlonly<script type="text/javascript">document.write("test" + randomUser2);</script>\endhtmlonly -n 127.0.0.1 -p 10000 -t hello
 * -d \htmlonly<script type="text/javascript">document.write("/tmp/test" + randomUser2 + "_workpacket_output");</script>\endhtmlonly -r
 * \htmlonly<script type="text/javascript">document.write("\'test" + randomUser2 + ".workdata1.instance1.workdata1\'");</script>\endhtmlonly -D</tt><p> This download step
 * should be possible with any datastore created.
 * 
 * \subsection fullyinstalled Secure Installation Complete
 * 
 * At this point, your installation is complete and fully secure.
 * This can now be used to send work over the Internet and organise
 * your HPC work load. */
